/*
 * Copyright 2011 Mark Davidson.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package org.dctmcommons;

import com.documentum.fc.client.DfServiceException;
import com.documentum.fc.client.IDfSession;
import com.documentum.fc.client.IDfSessionManager;
import com.documentum.fc.common.DfException;
import com.documentum.fc.common.IDfLoginInfo;

/**
 * Session-related helper methods.
 */
public interface ISessionHelper {

	/**
	 * Creates a session manager.
	 * @return The session manager
	 * @throws DfException
	 */
	public IDfSessionManager createSessionManager() throws DfException;

	/**
	 * Creates a session manager.
	 * @param repository The repository name
	 * @param username The username
	 * @param password The password
	 * @param domain The domain
	 * @return The session manager
	 * @throws DfException
	 */
	public IDfSessionManager createSessionManager(String repository,
												  String username,
												  String password,
												  String domain)
			throws DfException;

	/**
	 * Sets the identity.
	 * @param manager The session manager
	 * @param repository The repository
	 * @param username The username
	 * @param password The password
	 * @param domain The domain
	 * @throws DfServiceException
	 */
	public void setIdentity(IDfSessionManager manager,
							String repository,
							String username,
							String password,
							String domain)
			throws DfServiceException;

	/**
	 * Creates a {@link IDfLoginInfo} instance.
	 * @param username The username
	 * @param password The password
	 * @param domain The domain
	 * @return The login info
	 */
	public IDfLoginInfo createLoginInfo(String username,
										String password,
										String domain);

	/**
	 * Impersonates a user.
	 * @param session The superuser session
	 * @param username The user to impersonate
	 * @throws DfException
	 */
	public void impersonate(IDfSession session, String username)
			throws DfException;

	/**
	 * Releases a session.
	 * @param manager The session manager
	 * @param session The session
	 */
	public void releaseSession(IDfSessionManager manager,
							   IDfSession session);

	/**
	 * Releases a session.
	 * @param session The session
	 */
	public void releaseSession(IDfSession session);

	/**
	 * Instantiates, uses (via callback) and releases a session
	 * @param repository The repository
	 * @param username The username
	 * @param password The password
	 * @param domain The domain
	 * @param useTransaction Whether to use a transaction
	 * @param callback The callback
	 * @return The session manager
	 * @throws DfException The repository exception
	 */
	public IDfSessionManager useSession(String repository,
										String username,
										String password,
										String domain,
										boolean useTransaction,
										ISessionCallback callback)
			throws DfException;

	/**
	 * Instantiates, uses (via callback) and releases a session
	 * @param manager The session manager
	 * @param repository The repository
	 * @param useTransaction Whether to use a transaction
	 * @param callback The callback
	 * @throws DfException The repository exception
	 */
	public void useSession(IDfSessionManager manager,
						   String repository,
						   boolean useTransaction,
						   ISessionCallback callback) throws DfException;

}